home *** CD-ROM | disk | FTP | other *** search
/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_disks / 200-299 / ff290.lzh / IPC / Docs / Standard IDs < prev    next >
Text File  |  1989-12-11  |  9KB  |  202 lines
  1.  
  2.                  IPC Message and Item Standard ID Codes
  3.                  ======================================
  4.  
  5.                             -- May 1989 --
  6.  
  7. In a general InterProcess Communication system, messages should be able
  8. to contain or reference any kind of data relevant to that communication,
  9. from short text strings -- or even single-word codes -- to large bitmaps;
  10. each Server must know exactly what it is being passed.  One major goal
  11. of this IPC design is to make every message totally self-specifying, so
  12. that a Server receiving it can tell immediately what it contains and what
  13. to do with it (or alternatively that it does not recognize it and should
  14. reject it).  This is achieved by providing IDs both for the message as
  15. a whole and the items within it (as well as Flag fields -- described
  16. elsewhere -- that complete the information).  Some of these IDs will be
  17. relevant to individual Server functions, and will be defined by the
  18. developer, but others should have the same meaning wherever they are
  19. used, across the whole system.
  20.  
  21. For a full description of the IPCMessage structure please refer to the IPC
  22. Manual.  This note just lists the current set of IDs reserved for general
  23. use, and mentions some others that may be useful to adopt.
  24.  
  25. Remember that each ID is actually a 32-bit word, constructed from four
  26. upper-case ASCII characters (in standard 68000 data order, with the first
  27. character in the leftmost, most significant, 8 bits).  You can conveniently
  28. construct a fixed ID for your program with the MAKE_ID macro defined in
  29. IPC.h, or generate one at run-time with the MakeIPCId() library call.
  30.  
  31. Message IDs and Item IDs are distinct (though the same code value may be
  32. used for both on occasion).  The list below deals with Message IDs first,
  33. reserved codes followed by suggested ones, then deals similarly with
  34. Item IDs.
  35.  
  36.  
  37. Globally Reserved IPCMessage IDs:
  38. ================================
  39.  
  40. These IDs should not be given other meanings anywhere.  Only a few such
  41. seem necessary at the moment.
  42.  
  43.  
  44.     QUIT    --  Terminate program.
  45.                 Every Server should respond to this one, but the actual
  46.                 sequence of actions will have to depend on the situation:
  47.                 some Servers may have to defer exiting until they have
  48.                 finished any outstanding processing, others may just be
  49.                 able to reject any unanswered messages.  The Server may
  50.                 also have been asked to pass QUIT messages to others when
  51.                 it receives one itself.  A QUIT message may well have no
  52.                 items, but in some cases a single item may be included
  53.                 whose ID indicates more specific orders, such as:
  54.  
  55.                             IDLE    -- only quit if currently idle;
  56.                             QUIT    -- orderly exit NOW;
  57.                             PANC    -- get out now -- don't bother to
  58.                                        clean up! (only for debugging really).
  59.  
  60.  
  61.     CMND    --  General (standard format) Command message.
  62.                 Contains a program command in one of a small set of
  63.                 standard formats (probably can be considered equivalent
  64.                 to an ARexx message).  The first item will always be the
  65.                 command selector -- either a short ASCII string or a
  66.                 (32-bit) code word; its meaning will of course be a
  67.                 function of the Server.  Any arguments will be in the items
  68.                 following this; the actual contents and IDs of these will
  69.                 depend on the Server and the Clients it is intended to
  70.                 service, but for general servers they will probably just
  71.                 be strings.  Likely IDs (see Item IDs below):
  72.  
  73.                 Command Selector:   CODE, STRG.
  74.                 Arguments:          STRG, LINE. TEXT, INTG, REAL, CODE, etc.
  75.  
  76.  
  77.     MGMT    --  Management -- general requests to control IPC environment.
  78.                 This is not well defined at the moment, but we reserve it
  79.                 now, knowing that we'll need it later.  Possible items in
  80.                 this type of message include:
  81.  
  82.                         REQQ    --  Request that a QUIT message be sent to
  83.                         a specified IPCPort when this Server terminates.
  84.                         (Further specification of this still to come --
  85.                         for now assume just that ii_Ptr points to the port.)
  86.  
  87.                         MFIX    -- Memory fixing option; controls whether
  88.                         Server will exit when there are no Clients or
  89.                         remain in memory for later rapid response.  If Ptr
  90.                         field contains TRUE, Server will be fixed; if it is
  91.                         FALSE, Server will be freed.
  92.  
  93.  
  94.  
  95. Suggested message IDs:
  96. =====================
  97.  
  98. These aren't globally reserved, being specific to Server Ports -- and
  99. tentative in many cases --, but if they seem suitable it would probably be
  100. a good idea to use them.
  101.  
  102.     OUTA    --  send to output stream in ASCII (whatever output the Server
  103.                 generates based on the message, and whatever the Server's
  104.                 output stream currently is.)
  105.  
  106.     OUTB    --  send to output stream in Binary.
  107.  
  108.     CNVA    --  Convert to ASCII (whatever items, such as INTG and REAL,
  109.                 the Server is designed to handle; the resulting string may
  110.                 be passed back to the Client, or its disposition may be
  111.                 specified in the message -- see the demo "Print Format
  112.                 Server").
  113.  
  114.     MENU    --  request Menu setup (to be described elsewhere).
  115.  
  116.     MENI    --  request Menu Item setup ( "   " ).
  117.  
  118.  
  119.                                 # # #
  120.  
  121.  
  122. Globally Reserved IPCItem IDs:
  123. =============================
  124.  
  125. These should only be used -- in ANY message -- with the meanings specified
  126. here.  (Most Servers will only expect to encounter a small subset of them.)
  127. Most of them should be self-explanatory.
  128.  
  129.     LINE    --  A (complete) line of text -- null terminated, newline
  130.                 omitted.
  131.  
  132.     STRG    --  A null terminated text string -- no newlines (i.e. part of a
  133.                 line)
  134.  
  135.     TEXT    --  An arbitrary block of text -- may have newlines (or
  136.                 control characters etc.)
  137.  
  138.     PORT    --  An IPCPort pointer (A Server that intends to use this MUST
  139.                 call UseIPCPort() before replying the message this is in).
  140.  
  141.     MESG    --  A pointer to an IPCMessage block (with restrictions -- to be
  142.                 detailed later).
  143.  
  144.     CODE    --  A 32-bit code value (maybe an IPC ID)
  145.  
  146.     FILH    --  An AmigaDOS FILe Handle
  147.  
  148.     INTG    --  A (32-bit) INTeGer
  149.  
  150.     CHAR    --  single 8-bit character (in low byte)
  151.  
  152.     REAL    --  pointer to an IEEE floating point number (double)
  153.  
  154.     PRVT    --  private item of concern to originating client only. (Can
  155.                 be used by a Client to mark a message for later
  156.                 identification, with a sequence number, for instance.)
  157.  
  158.     NULL    --  what it says -- used as a spacer or for cancelling things
  159.                 without having to rebuild the message.
  160.  
  161.  
  162.  
  163. Other suggested string valued Items:
  164. ===================================
  165.  
  166. (currently used, or intended to be)
  167.  
  168.     RETS    --  RETurn String  (a slot provided by the Client for the
  169.                 Server to fill in; it may initially either be empty, in
  170.                 which case the Server allocates suitable memory, or already
  171.                 allocated, in chich case the Server will write into it
  172.                 -- taking care not to overflow, of course!).
  173.  
  174.  
  175.     FILN    --  FILe Name
  176.  
  177.     DIRN    --  DIRectory Name
  178.  
  179.     PATS    --  PATtern String (possibly containing special pattern
  180.                 characters; the actual format would be Server -- and
  181.                 Message ID -- dependent; e.g. it might be a 'printf' type
  182.                 format, or a regular-expression pattern matching string).
  183.  
  184.  
  185. Other possible item IDs:
  186. =======================
  187.  
  188. (currently used in at least one program)
  189.  
  190.     MARK    --  32-bit private client code to be copied to any message
  191.                 generated on the basis of this one; in other words the
  192.                 Server generates one or more new messages, from some or
  193.                 all of the items in this one, which will eventually get
  194.                 back to the Client; the Client can use this item to
  195.                 determine the original source, for example to put it in
  196.                 the correct list.  This ID may be globally reserved
  197.                 eventually.
  198.  
  199.  
  200.                                 # # #
  201.  
  202.